Skip to content

Add support for forwarding headers from MCP clients to GraphQL APIs #428

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 4 commits into
base: develop
Choose a base branch
from
Open

Add support for forwarding headers from MCP clients to GraphQL APIs #428

wants to merge 4 commits into from
+379 −33

Conversation

DaleSeo
Copy link
Contributor

@DaleSeo DaleSeo commented Oct 7, 2025 •
edited
Loading

Fixes #198

Adds opt-in support for dynamic header forwarding, which enables metadata for A/B testing, feature flagging, geo information from CDNs, or internal instrumentation to be sent from MCP clients to downstream GraphQL APIs. It automatically blocks hop-by-hop headers according to the guidelines in RFC 7230, section 6.1, and it only works with the Streamable HTTP transport.

You can configure using the forward_headers setting:

forward_headers:
  - x-tenant-id
  - x-experiment-id
  - x-geo-country

Please note that this feature is not intended for passing through credentials as documented in the best practices page.

E2E Test

Configure the MCP server to target the Platform API and enable CORS as below, then verify end‑to‑end with MCP Inspector:

endpoint: https://api.apollographql.com/api/graphql
cors:
  enabled: true
  match_origins:
    - "^http://localhost:[0-9]+$"
  allow_headers:
    - accept
    - content-type
    - mcp-protocol-version
    - mcp-session-id
    - traceparent
    - tracestate
    - x-custom-auth-headers
    - X-API-Key
    - apollographql-client-name
    - apollographql-client-version
forward_headers:
  - X-API-Key
  - apollographql-client-name
  - apollographql-client-version
transport:
  type: streamable_http
  port: 8000

With the 3 required headers set in MCP Inspector, tool execution succeeds:

2025-10-08 at 17 06 00

If you configure MCP Inspector with Connection Type = Direct, you can also inspect the MCP call in the browser:

2025-10-08 at 17 20 27

If any required header is missing, the server returns an error:

2025-10-08 at 17 18 18

@DaleSeo DaleSeo self-assigned this Oct 7, 2025
@apollo-librarian
Copy link

apollo-librarian bot commented Oct 7, 2025 •
edited
Loading

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 8 changed, 0 removed 
* (developer-tools)/apollo-mcp-server/(latest)/best-practices.mdx
* (developer-tools)/apollo-mcp-server/(latest)/config-file.mdx
* (developer-tools)/apollo-mcp-server/(latest)/deploy.mdx
* (developer-tools)/apollo-mcp-server/(latest)/index.mdx
* (developer-tools)/apollo-mcp-server/(latest)/limitations.mdx
* (developer-tools)/apollo-mcp-server/(latest)/quickstart.mdx
* (developer-tools)/apollo-mcp-server/(latest)/telemetry.mdx
* (developer-tools)/apollo-mcp-server/(latest)/_sidebar.yaml

Build ID: a7fa14ebf9e66e0b65c8094e
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/a7fa14ebf9e66e0b65c8094e

@swcollard swcollard mentioned this pull request Oct 8, 2025
Closed
@DaleSeo DaleSeo marked this pull request as ready for review October 8, 2025 21:39
@DaleSeo DaleSeo requested review from a team as code owners October 8, 2025 21:39
@github-actions GitHub Actions
Copy link

github-actions bot commented Oct 8, 2025

❌ Changeset file missing for PR

All changes should include an associated changeset file.
Please refer to README for more information on generating changesets.

swcollard
swcollard reviewed Oct 9, 2025
View reviewed changes
crates/apollo-mcp-server/src/headers.rs
use crate::auth::ValidToken;

/// List of header names to forward from MCP clients to GraphQL API
pub type ForwardHeaders = Vec<String>;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want any additional validation on the strings being used here? Like size limits, or excludes mcp-session-id, authorization, traceparent, and tracestate which we tend to handle more as special cases?

Copy link
Contributor Author

@DaleSeo DaleSeo Oct 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great question, @swcollard ! Which of them do you think we should block from forwarding? I guess forwarding mcp-session-id, traceparent and tracestate to downstream APIs could be helpful from the observability perspective? 🤔 We recommend not using this feature for passing through authorization in the best practices docs, but I think we should still leave it to the user's discretion based on customer feedback.

@DaleSeo DaleSeo requested a review from swcollard October 9, 2025 21:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@swcollard swcollard Awaiting requested review from swcollard

At least 1 approving review is required to merge this pull request.

Assignees

@DaleSeo DaleSeo

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@DaleSeo @swcollard